3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Accessing Memory Storage Objects

QuickDraw 3D provides routines for creating and managing memory storage objects.

Q3MemoryStorage_New

You can use the Q3MemoryStorage_New function to create a new memory storage object.



 
TQ3StorageObject Q3MemoryStorage_New (

                     const unsigned char *buffer, 

                     unsigned long validSize);

buffer: A pointer to a buffer in memory, or NULL .
validSize: The size, in bytes, of the valid metafile data contained in the specified buffer. If buffer is set to NULL , this parameter specifies the initial size and also the grow size of the buffer that QuickDraw 3D allocates internally.

DESCRIPTION

The Q3MemoryStorage_New function returns, as its function result, a new memory storage object associated with the data in the buffer specified by the buffer and validSize parameters. The data in the specified buffer is copied into internal QuickDraw 3D memory, so you can dispose of the buffer if Q3MemoryStorage_New returns successfully.

If you pass the value NULL in the buffer parameter, QuickDraw 3D allocates a buffer of validSize bytes, increases the buffer by that size whenever necessary, and later disposes of the buffer when the associated storage object is closed or disposed of. If buffer is set to NULL and validSize is set to 0, QuickDraw 3D uses a default initial buffer and grow size.

If Q3MemoryStorage_New cannot create a new storage object, it returns the value NULL .

ERRORS

kQ3ErrorOutOfMemory

Q3MemoryStorage_NewBuffer

You can use the Q3MemoryStorage_NewBuffer function to create a new memory storage object. The data you provide is not copied into QuickDraw 3D memory.



 
TQ3StorageObject Q3MemoryStorage_NewBuffer (

                     unsigned char *buffer, 

                     unsigned long validSize, 

                     unsigned long bufferSize);

buffer: A pointer to a buffer in memory, or NULL .
validSize: The size, in bytes, of the valid metafile data contained in the specified buffer. If buffer is set to NULL , this parameter specifies the initial size and also the grow size of the buffer that QuickDraw 3D allocates internally.
bufferSize: The size, in bytes, of the specified buffer.

DESCRIPTION

The Q3MemoryStorage_NewBuffer function returns, as its function result, a new memory storage object associated with the buffer specified by the buffer and validSize parameters. The data in the specified buffer is not copied into internal QuickDraw 3D memory, so your application must not access that buffer until the associated storage object is closed or disposed of.

The bufferSize parameter specifies the size of the specified buffer. The validSize parameter specifies the size of the valid metafile data contained in the buffer. The value of the validSize parameter should always be less than or equal to the value of the bufferSize parameter. This allows you to maintain other data in the buffer following the valid metafile data.

If Q3MemoryStorage_NewBuffer cannot create a new storage object, it returns the value NULL .

ERRORS

kQ3ErrorOutOfMemory

Q3MemoryStorage_Set

You can use the Q3MemoryStorage_Set function to set the data of a memory storage object.



 
TQ3Status Q3MemoryStorage_Set (

                     TQ3StorageObject storage, 

                     const unsigned char *buffer, 

                     unsigned long validSize);

storage: A memory storage object.
buffer: A pointer to a contiguous block of memory to be associated with the specified storage object, or NULL .
validSize: The size, in bytes, of the valid metafile data contained in the specified buffer. If buffer is set to NULL , this parameter specifies the initial size and also the grow size of the buffer that QuickDraw 3D allocates internally.

DESCRIPTION

The Q3MemoryStorage_Set function sets the data for the memory storage object specified by the storage parameter to the values specified in the buffer and validSize parameters. The data in the specified buffer is copied into internal QuickDraw 3D memory, so you can dispose of the buffer if Q3MemoryStorage_Set returns successfully.

If you pass the value NULL in the buffer parameter, QuickDraw 3D allocates a buffer of validSize bytes, increases the buffer by that size whenever necessary, and later disposes of the buffer when the associated storage object is closed or disposed of. If buffer is set to NULL and validSize is set to 0, and if the buffer parameter was set to NULL when the storage object was created, QuickDraw 3D uses a default initial buffer and grow size.

SPECIAL CONSIDERATIONS

You must not use Q3MemoryStorage_Set with an open memory storage object.

ERRORS

kQ3ErrorAccessRestricted kQ3ErrorInvalidObjectParameter

Q3MemoryStorage_GetBuffer

You can use the Q3MemoryStorage_GetBuffer function to get the data of a memory storage object.



 
TQ3Status Q3MemoryStorage_GetBuffer (

                     TQ3StorageObject storage, 

                     unsigned char **buffer, 

                     unsigned long *validSize, 

                     unsigned long *bufferSize);

storage: A memory storage object.
buffer: On entry, a pointer to a pointer. On exit, a pointer to a pointer to the block of memory associated with the specified storage object.
validSize: On exit, the size, in bytes, of the valid metafile data contained in the specified buffer.
bufferSize: On exit, the size, in bytes, of the block of memory whose address is returned through the buffer parameter.

DESCRIPTION

The Q3MemoryStorage_GetBuffer function returns, in the buffer and bufferSize parameters, the address and size of the block of memory currently associated with the memory storage object specified by the storage parameter. Note that the returned address is the address of the storage object's data, not of a copy of that data. As a result, the returned pointer may become a dangling pointer if the buffer holding the storage object's data is dynamically reallocated (perhaps because additional data was written to the object).

ERRORS

kQ3ErrorAccessRestricted kQ3ErrorInvalidObjectParameter

Q3MemoryStorage_SetBuffer

You can use the Q3MemoryStorage_SetBuffer function to set the data of a memory storage object.



 
TQ3Status Q3MemoryStorage_SetBuffer (

                     TQ3StorageObject storage, 

                     unsigned char *buffer, 

                     unsigned long validSize, 

                     unsigned long bufferSize);

storage: A memory storage object.
buffer: A pointer to a block of memory to be associated with the specified storage object, or NULL .
validSize: The size, in bytes, of the valid metafile data contained in the specified buffer. If the value of buffer is NULL , this parameter specifies the initial size and also the grow size of the buffer that QuickDraw 3D allocates internally.
bufferSize: The size, in bytes, of the specified buffer.

DESCRIPTION

The Q3MemoryStorage_SetBuffer function sets the buffer location, size, and valid size of the memory storage object specified by the storage parameter to the values specified in the buffer , bufferSize , and validSize parameters.

SPECIAL CONSIDERATIONS

You must not use Q3MemoryStorage_SetBuffer with an open memory storage object.

Q3MemoryStorage_GetType

You can use the Q3MemoryStorage_GetType function to get the type of a memory storage object.



 
TQ3ObjectType Q3MemoryStorage_GetType (TQ3StorageObject storage);

storage: A memory storage object.

DESCRIPTION

The Q3MemoryStorage_GetType function returns, as its function result, the type of the memory storage object specified by the storage parameter. The types of memory storage objects currently supported by QuickDraw 3D are defined by this constant:



 
kQ3MemoryStorageTypeHandle

If the specified memory storage object is invalid or is not of this type, Q3MemoryStorage_GetType returns the value kQ3ObjectTypeInvalid .

ERRORS

kQ3ErrorNoSubclass kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter